[SPARK-31738][SQL][DOCS] Describe 'L' and 'M' month pattern letters #28558
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
Author
|
@cloud-fan @HyukjinKwon @xuanyuanking Please, review this PR. |
MaxGekk
changed the title
|
Test build #122759 has finished for PR 28558 at commit
|
cloud-fan
reviewed
May 18, 2020
docs/sql-ref-datetime-pattern.md
Outdated
|
|
||
| - Year: The count of letters determines the minimum field width below which padding is used. If the count of letters is two, then a reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will parse using the base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. If the count of letters is less than four (but not two), then the sign is only output for negative years. Otherwise, the sign is output if the pad width is exceeded when 'G' is not present. | ||
|
|
||
| - Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number. The text form is depend on letters - 'M' denotes the 'standard' form, and 'L' is for 'stand-alone' form. The difference between the 'standard' and 'stand-alone' forms is trickier to describe as there is no difference in English. However, in other languages there is a difference in the word used when the text is used alone, as opposed to in a complete date. For example, the word used for a month when used alone in a date picker is different to the word used for month in association with a day and year in a date. Here are examples for all supported pattern letters: |
Contributor
There was a problem hiding this comment.
we can give an example in Russia.
Member
Author
There was a problem hiding this comment.
The PR contains examples in Russian already
Contributor
There was a problem hiding this comment.
It's better to give a quick example here, so that some users can stop reading the following detailed examples to save time.
cloud-fan
reviewed
May 18, 2020
| spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'LLLL', 'locale', 'RU')); | ||
| январь | ||
| ``` | ||
| - `'LLLLL'` or `'MMMMM'`: Narrow textual representation of standard or stand-alone forms. Typically it is a single letter. |
Member
Author
There was a problem hiding this comment.
I demonstrate only supported patterns
Contributor
There was a problem hiding this comment.
do we document somewhere that 6 or more L/Ms are invalid?
Member
Author
There was a problem hiding this comment.
I wrote above that this is the list of all supported patterns or do you think it is not enough?
Contributor
There was a problem hiding this comment.
how about
Here are examples for all supported pattern letters (more than 5 letter is invalid):
docs/sql-ref-datetime-pattern.md
Outdated
|
|
||
| - Year: The count of letters determines the minimum field width below which padding is used. If the count of letters is two, then a reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will parse using the base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. If the count of letters is less than four (but not two), then the sign is only output for negative years. Otherwise, the sign is output if the pad width is exceeded when 'G' is not present. | ||
|
|
||
| - Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number. The text form is depend on letters - 'M' denotes the 'standard' form, and 'L' is for 'stand-alone' form. The difference between the 'standard' and 'stand-alone' forms is trickier to describe as there is no difference in English. However, in other languages there is a difference in the word used when the text is used alone, as opposed to in a complete date. For example, the word used for a month when used alone in a date picker is different to the word used for month in association with a day and year in a date. Here are examples for all supported pattern letters: |
Member
There was a problem hiding this comment.
Do we also need to add an extra official description link for the 'standard' and 'standalone' mode?
Member
Author
There was a problem hiding this comment.
This is the official doc, isn't it as we decided to not refer to Java doc anymore.
|
Test build #122790 has finished for PR 28558 at commit
|
Contributor
|
thanks, merging to master/3.0! |
cloud-fan
pushed a commit
that referenced
this pull request
May 18, 2020
### What changes were proposed in this pull request? 1. Describe standard 'M' and stand-alone 'L' text forms 2. Add examples for all supported number of month letters <img width="1047" alt="Screenshot 2020-05-18 at 08 57 31" src="https://user-images.githubusercontent.com/1580697/82178856-b16f1000-98e5-11ea-87c0-456ef94dcd43.png"> ### Why are the changes needed? To improve docs and show how to use month patterns. ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? By building docs and checking by eyes. Closes #28558 from MaxGekk/describe-L-M-date-pattern. Authored-by: Max Gekk <max.gekk@gmail.com> Signed-off-by: Wenchen Fan <wenchen@databricks.com> (cherry picked from commit b3686a7) Signed-off-by: Wenchen Fan <wenchen@databricks.com>
Member
|
+1 seems good to me too |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What changes were proposed in this pull request?
Why are the changes needed?
To improve docs and show how to use month patterns.
Does this PR introduce any user-facing change?
No
How was this patch tested?
By building docs and checking by eyes.